// Copyright 2024 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package truth

import (
	"fmt"

	"go.chromium.org/luci/common/testing/truth/failure"
)

// summaryModifier is the implementation of ModifySummary - this arrangement is
// so that ModifySummary shows up next to Option in godocs.
type summaryModifier func(*failure.Summary)

func (summaryModifier) truthOption() {}

// ModifySummary is an Option which modifies the *failure.Summary
// of a failing comparison.
//
// Example:
//
//	truth.Assert(t, 100, should.Equal(1), truth.ModifySummary(func(s *failure.Summary) {
//	  s.Findings = append(s.Findings, &failure.Finding{Name: "Extra finding!"})
//	})
//
// In this example, if 100 does not equal 1, this callback will be
// invoked on the *failure.Summary generated by should.Equal.
//
// This will never be invoked with a nil *Summary.
func ModifySummary(cb func(*failure.Summary)) Option {
	return summaryModifier(cb)
}

// Explain is an Option which adds a new finding "Explaination" to the
// *failure.Summary of the failing comparison.
//
// Example:
//
//	truth.Assert(t, wingie[i].cool(), should.BeTrue, truth.Explain(
//	  "wingie number %d was not cool"))
func Explain(format string, args ...any) Option {
	return ModifySummary(func(s *failure.Summary) {
		s.Findings = append(s.Findings, &failure.Finding{
			Name:  "Explaination",
			Value: []string{fmt.Sprintf(format, args...)},
		})
	})
}
